Forecasting Service
[BETA] Inventory-level Forecasts
Get inventory forecasts for the given inventory items and time window.
⚠️ Beta Access Required
Contact your sales representative to gain access to this endpoint and start using it.
It returns a list of daily forecasts for the following metrics:
- Total number of auctions.
- Total number of slots.
- Total number of winners.
- Total number of impressions.
- Total number of clicks.
- Average CPC.
- Average CTR.
- Slot occupancy (Proportion of slots that are occupied).
- Total capacity (represents the potential revenue that could be generated under optimal conditions).
- Occupied capacity (reflects the actual revenue generated from effective winners and active campaigns).
POST
/
public
/
v1
/
toptimize
/
forecasting
/
inventory
Copy
Ask AI
curl --request POST \
--url https://api.topsort.com/public/v1/toptimize/forecasting/inventory \
--header 'Content-Type: application/json' \
--data '{
"inventory": [
{
"inventoryType": "category",
"inventoryValue": "<string>"
}
],
"timeWindow": 7
}'Copy
Ask AI
[
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "category",
"inventoryValue": "electronics"
},
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "search",
"inventoryValue": "smartphone"
}
]Assistant
Responses are generated using AI and may contain mistakes.
Body
application/json
Request model for batch inventory forecasts.
Response
200
application/json
Successful Response
The response is of type InventoryForecast · object[].
Copy
Ask AI
curl --request POST \
--url https://api.topsort.com/public/v1/toptimize/forecasting/inventory \
--header 'Content-Type: application/json' \
--data '{
"inventory": [
{
"inventoryType": "category",
"inventoryValue": "<string>"
}
],
"timeWindow": 7
}'Copy
Ask AI
[
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "category",
"inventoryValue": "electronics"
},
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "search",
"inventoryValue": "smartphone"
}
]Auction examples
- Running auctions
- Sponsored listings
- Sponsored banners
- Sponsored brands
Asset examples
Webhook examples
Assets API
Billing API
- GETGet Billing Contacts
- GETGet Billing Contact
- PUTUpsert Billing Contact
- GETGet Campaign Billing Contact
- PUTUpsert Campaign Billing Contact
- GETGet Marketplace Credit Limitdeprecated
- POSTSet Marketplace Credit Limitdeprecated
- PUTUpsert Vendor Billing Contact
- GETGet Vendor Chargesdeprecated
- GETGet Vendor Account Activitydeprecated
- GETGet Vendor Balance
- POSTAdd Vendor Balance
- POSTBurn Vendor Balance
- GETGet Vendor Credit Historydeprecated
- GETGet Vendor Credit Limitdeprecated
- POSTSet Vendor Credit Limitdeprecated
- DELDelete Vendor Billing Contact
- GETGet Vendor Wallets
- POSTCreate Wallet
- POSTAdjust Wallet Balance
Campaign API
- GETGet Campaigns
- POSTCreate Campaign
- GETGet Campaign By Id
- DELDelete Campaign By Id
- PATCHUpdate Campaign By Id
- GETGet Campaign Bids
- POSTCreate Campaign Bids
- DELDelete Campaign Bid By Id
- PATCHUpdate Campaign Bid By Id
- GETGet Campaign Restriction
- POSTCreate Campaign Restriction
- PATCHUpdate Campaign Restriction
- POST[BETA] Get estimated clicks of a future campaign for a given vendordeprecated
- GETGet Products In Campaign
- GETGet Restriction Types
- GETGet Restriction Type
- GETGet Sponsored Productsdeprecated
Catalog API
Invitation API
Offsite Ads API
- PUTUpsert Advertiser Domain
- POSTCreate a new advertiser
- GETGet advertiser onboarding state for a specific DSP
- GETGet vendor offsite campaigns
- POSTCreate Campaign
- GETGet campaign information
- PATCHUpdate Campaign
- GETGet Job Status
- GETGet Campaign Aggregated Report
- GETGet Campaign Daily Report
- GETGet Campaign Products Report
Reporting API
- GETGet Campaign Report
- GETGet Campaign Daily Report
- GETGet Campaign Report By Product
- GETGet Product Report
- GETGet Product Daily Report
- GETGet Interactions Dump Urls
- GETGet Scored Attribution Dump Urls
- GETGet Marketplace Interactions Report
- GETGet Marketplace Report
- GETGet Marketplace Campaigns Kpis
- GETGet Marketplace Daily Report
- GETGet Marketplace Vendors Kpis
- GETGet Vendor Report
- GETGet Vendor Daily Report
Segments Service
Toppie API
- GET[BETA] Get Toppie Campaigns
- POST[BETA] Create Toppie Campaign
- GET[BETA] Get Toppie Campaign Details
- DEL[BETA] Delete Toppie Campaign
- PATCH[BETA] Update Toppie Campaign
- GET[BETA] Get Toppie Campaign Bids
- GET[BETA] List Account Products
- GET[BETA] Get Agency Account Report.
- GET[BETA] Account Activity Reports.
- GET[BETA] Get Campaigns Reporting.
- GET[BETA] Get Campaign Report.
- GET[BETA] Get Campaign Products Report.
- GETGet Agency Daily Kpis By Product Dump Urls
Forecasting Service
Forecasting Service
[BETA] Inventory-level Forecasts
Get inventory forecasts for the given inventory items and time window.
⚠️ Beta Access Required
Contact your sales representative to gain access to this endpoint and start using it.
It returns a list of daily forecasts for the following metrics:
- Total number of auctions.
- Total number of slots.
- Total number of winners.
- Total number of impressions.
- Total number of clicks.
- Average CPC.
- Average CTR.
- Slot occupancy (Proportion of slots that are occupied).
- Total capacity (represents the potential revenue that could be generated under optimal conditions).
- Occupied capacity (reflects the actual revenue generated from effective winners and active campaigns).
POST
/
public
/
v1
/
toptimize
/
forecasting
/
inventory
Copy
Ask AI
curl --request POST \
--url https://api.topsort.com/public/v1/toptimize/forecasting/inventory \
--header 'Content-Type: application/json' \
--data '{
"inventory": [
{
"inventoryType": "category",
"inventoryValue": "<string>"
}
],
"timeWindow": 7
}'Copy
Ask AI
[
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "category",
"inventoryValue": "electronics"
},
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "search",
"inventoryValue": "smartphone"
}
]Assistant
Responses are generated using AI and may contain mistakes.
Body
application/json
Request model for batch inventory forecasts.
Response
200
application/json
Successful Response
The response is of type InventoryForecast · object[].
Copy
Ask AI
curl --request POST \
--url https://api.topsort.com/public/v1/toptimize/forecasting/inventory \
--header 'Content-Type: application/json' \
--data '{
"inventory": [
{
"inventoryType": "category",
"inventoryValue": "<string>"
}
],
"timeWindow": 7
}'Copy
Ask AI
[
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "category",
"inventoryValue": "electronics"
},
{
"dailyForecasts": [
{
"forecastDate": "2025-01-15",
"metrics": [
{
"metricName": "total_auctions",
"values": {
"forecastIntervalMax": 13200,
"forecastIntervalMin": 11800,
"forecastValue": 12500
}
},
{
"metricName": "total_slots",
"values": {
"forecastIntervalMax": 26500,
"forecastIntervalMin": 23500,
"forecastValue": 25000
}
},
{
"metricName": "total_winners",
"values": {
"forecastIntervalMax": 9300,
"forecastIntervalMin": 8200,
"forecastValue": 8750
}
},
{
"metricName": "total_impressions",
"values": {
"forecastIntervalMax": 19900,
"forecastIntervalMin": 17600,
"forecastValue": 18750
}
},
{
"metricName": "total_clicks",
"values": {
"forecastIntervalMax": 4000,
"forecastIntervalMin": 3500,
"forecastValue": 3750
}
},
{
"metricName": "avg_cpc",
"values": {
"forecastIntervalMax": 3,
"forecastIntervalMin": 2.7,
"forecastValue": 2.85
}
},
{
"metricName": "avg_ctr",
"values": {
"forecastIntervalMax": 0.22,
"forecastIntervalMin": 0.18,
"forecastValue": 0.2
}
},
{
"metricName": "slot_occupancy",
"values": {
"forecastIntervalMax": 0.75,
"forecastIntervalMin": 0.65,
"forecastValue": 0.7
}
},
{
"metricName": "total_capacity",
"values": {
"forecastIntervalMax": 132000,
"forecastIntervalMin": 118000,
"forecastValue": 125000
}
},
{
"metricName": "occupied_capacity",
"values": {
"forecastIntervalMax": 93000,
"forecastIntervalMin": 82000,
"forecastValue": 87500
}
}
]
}
],
"inventoryType": "search",
"inventoryValue": "smartphone"
}
]